SGI MineSet 2.5/SGI MineSet 2.5.iso/dist/imgtools.idb/usr/share/catman/u_man/cat1/imgtcl.z/imgtcl

Text File | 1998-05-12 | 13KB | 397 lines

iiiimmmmggggttttccccllll((((1111))))                                                            iiiimmmmggggttttccccllll((((1111))))



NNNNAAAAMMMMEEEE
     iiiimmmmggggttttccccllll - tcl-based scripting shell for the IL


SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     iiiimmmmggggttttccccllll [_f_i_l_e_n_a_m_e _a_r_g_1 _a_r_g_2... ]


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The imgtcl shell provides a tcl-based scripting interface to the IL.  IL
     operators and image files can be created, linked together, and displayed
     in an ilViewer or ilDisplay object.  Most of the IL's classes can be be
     created and manipulated within imgtcl; multi-dimensional arrays can also
     be allocated (usually to be used as parameters to an IL function.)


   IIIInnnnvvvvooookkkkiiiinnnngggg IIIILLLL ffffuuuunnnnccccttttiiiioooonnnnssss
     The various constructors and methods defined by the IL are available as
     imgtcl commands; default values, where defined, are supported by imgtcl.
     If a constructor or method has overloaded versions, then the alternative
     versions will have a slightly different name; these names are shown in
     the header file for that class.  For instance, the iiiillllFFFFiiiilllleeeeIIIImmmmgggg object has
     four different constructors; in imgtcl they are named:

          ilFileImgOpen - opens an existing file by name

          ilFileImgOpenByDescriptor - opens an existing file by descriptor

          ilFileImgCreate - creates a new file

          ilFileImgCreateByDescriptor - creates a new file by descriptor

     if there is a return value, it will be converted to an ASCII string and
     returned as the value of the command.  Many of the IL functions will
     return a pointer value; it will be converted to the string:

          (type-name*)address

     where <type-name> is the type of the pointer being returned and address
     is the hex address of the pointer (e.g. "(ilFileImg*)0x00100fe0").


   CCCCrrrreeeeaaaattttiiiinnnngggg IIIILLLL oooobbbbjjjjeeeeccccttttssss
     In general, class constructors are available as imgtcl commands; the
     syntax is:

          <object-type> <name> args

     Where <object-type> is the C++ name of the class (or an alternative, if
     the constructor is overloaded), <name> is a unique identifier used to
     name the new object, and args is a list of arguments to the constructor
     (default values as defined in the header file are supported).  The



                                                                        PPPPaaaaggggeeee 1111






iiiimmmmggggttttccccllll((((1111))))                                                            iiiimmmmggggttttccccllll((((1111))))



     object's name is returned as the value of the command.

     For example, the command:

          ilFileImgOpen sfoimg /images/sfo.fit

     will open the image file "/images/sfo.fit", create an ilFileImg object
     named "sfoimg" and return that name.

     As a side effect of creating an IL object, a new imgtcl command is
     created using the object's name.  This command gives access to the C++
     methods of that object's class and its base classes.  For example, after
     the above call to create "sfoimg", the command:

          sfoimg getFileName

     will return the value "/images/sfo.fit", the name of the file.  Any
     arguments should follow the method name.


   FFFFuuuunnnnccccttttiiiioooonnnn aaaannnndddd mmmmeeeetttthhhhoooodddd aaaarrrrgggguuuummmmeeeennnnttttssss
     The imgtcl interpreter is aware of the types of each functions's
     arguments, and will try to convert each string argument to the
     appropriate type.  For numeric or string arguments, the conversion is
     simple.  When an argument is an object, imgtcl will accept either the
     name of the object (e.g. "sfoimg") or the object's address, expressed as
     a string (e.g. 0x0010fe80).  Care must be taken when passing literal
     addresses, as an incorrect address can cause a bus error (or other
     unpredictable problems).


   VVVViiiieeeewwwwiiiinnnngggg iiiimmmmaaaaggggeeeessss
     To view a single image object, just type that object's name on a command
     line by itself; this will create an ilViewer window and display the image
     in that viewer.  While the viewer is active, the imgtcl interpreter will
     be suspended; when the viewer window is closed, the imgtcl prompt will
     again be issued.

     When viewing more than one object, the "view" command may be used.  For
     example, if there are image objects "sfoimg" and "convimg", the command
     "view sfoimg convimg" will bring up a viewer with those two images
     displayed, one on top of the other.


   CCCCrrrreeeeaaaattttiiiinnnngggg aaaarrrrrrrraaaayyyyssss wwwwiiiitttthhhh nnnneeeewwww
     Some methods require array arguments, and imgtcl provides the command
     "new" for the purpose of creating and initializing arrays.  The syntax
     for new is:

          new <elem-type> [name] <dims> [= <initializer>]





                                                                        PPPPaaaaggggeeee 2222






iiiimmmmggggttttccccllll((((1111))))                                                            iiiimmmmggggttttccccllll((((1111))))



     where <elem-type> is the C++ data type of the array elements (the simple
     types int, float, etc are supported, as well as many of the IL's struct
     types); <name> is a variable name that is to receive the address and
     dimension info of the array; <dims> is a list of integers defining the
     size of the array, and <initializer> is a list containing the values used
     to initialize the array.  For multi-dimensional arrays, enclose each
     dimension in a set of braces {}.  If the array elements are structs, list
     the field names in order.

     The optional <name> argument shown above can be used to retrieve and set
     the values stored in the array, and to delete the array.

     EEEExxxxaaaammmmpppplllleeee::::

     imgtcl> new int {2 2} = { {1 2} {3 4} }

     This command creates a 2x2 int array and initializes it to contain:

     array[0][0] = 1
     array[0][1] = 2
     array[1][0] = 3
     array[1][1] = 4

     The next example creates an array of iflXYfloats with the indicated {x,y}
     values, and stores the address and dimension info in the variable "xy";
     this variable is then used to print the values in the array, and then
     change the values stored in the array:

     imgtcl> new iflXYfloat xy {3} = { {0 0} {39 71} {266 271} }
     (iflXYfloat {3})0x1000a040
     imgtcl> echo $xy
     (iflXYfloat {3})0x1000a040
     imgtcl> $xy
     {0 0} {39 71} {266 271}
     imgtcl> $xy = { {42 268} {147 264} {265 263} }
     imgtcl> $xy
     {42 268} {147 264} {265 263}

     Notice that the "new" command returns the same string that the variable
     "xy" is set to.


   BBBBuuuuiiiilllltttt----iiiinnnn ccccoooommmmmmmmaaaannnnddddssss
     In addition to the complete external API of IL and IFL, several
     convenient built-in functions are provided.

     ttttiiiimmmmeeeessss

          times






                                                                        PPPPaaaaggggeeee 3333






iiiimmmmggggttttccccllll((((1111))))                                                            iiiimmmmggggttttccccllll((((1111))))



          Returns the value returned by the Unix call times(2).

     mmmmaaaalllllllloooocccc

          malloc _n


          Returns the pointer resulting from malloc'ing _n bytes.

     ffffrrrreeeeeeee

          free _p


          Free the previously malloc'ed pointer.

     ggggeeeettttoooopppptttt

          getopt _a_r_g_c _a_r_g_v _o_p_t_s_p_e_c


          Emulate the Unix getopt facility.  The arguments to the command
          include the command-line arguments and a option specifier string.
          The command-line arguments are expected to be in conventional C
          form.  That is, the array _a_r_g_v is zero-indexed with the zero-th
          argument being the command name.  The format of the option specifier
          is described in getopt(3C).

          Here is an example:

          #!/usr/sbin/imgtcl
          # mangle args to match our getopt expectations
          incr argc
          set argv [linsert $argv 0 $argv0]
          # check for command line options
          while {[string compare [set c [getopt $argc $argv  "ab:c:"]] EOF] != 0} {
              switch $c {
                  a {set aFlag 1}
                  b {set bArg $optarg}
                  c {set cArg $optarg}
              }
          }
          # ... do processing ...


     xxxxooooppppeeeennnnddddiiiissssppppllllaaaayyyy

          xopendisplay _d_i_s_p_N_a_m_e=NULL







                                                                        PPPPaaaaggggeeee 4444






iiiimmmmggggttttccccllll((((1111))))                                                            iiiimmmmggggttttccccllll((((1111))))



          Returns the X Display pointer associated with _d_i_s_p_l_a_y_N_a_m_e that
          results from the X call XOpenDisplay(3X11).

     xxxxcccclllloooosssseeeeddddiiiissssppppllllaaaayyyy

          xclosedisplay _p


          Returns the integer value returned by calling XCloseDisplay(3X11)
          with the previously-opened display pointer _p.

     vvvviiiieeeewwww

          view _i_m_g_1 ...


          Display a viewer, similar to imgview(1), one or more image objects.
          The viewer is retained between calls to vvvviiiieeeewwww.  Therefore, its state,
          such as being double- or single-buffered, or being in an RGB or
          pseudo color rendering mode.

     ddddiiiissssppppllllaaaayyyy

          display _d_i_s_p _w _h
          display _d_i_s_p _i_m_g


          An ilDisplay object is constructed and returned as the "command"
          named _d_i_s_p.  After the display is constructed, methods on ilDisplay
          can be invoked in the standard manner.

     rrrreeeeaaaaddddbbbbaaaacccckkkk

          readback _m_e_m _i_m_g


          The image _i_m_g is displayed and readback into a memory image.  The
          result is readback in the RGBA unsigned byte format, regardless of
          the format of the image.  If the input image has no alpha, the alpha
          channel is initialized to a constant 255.

     ttttiiiimmmmeeeeppppaaaaiiiinnnntttt

          timepaint _d_i_s_p


          Precisely time the length of the ppppaaaaiiiinnnntttt() method call on _d_i_s_p.  The
          result is returned in seconds.  This function uses ilTimer(3) to
          time the interval.  Note that the elapsed time to paint the view
          will not include the time to compute outstanding graphics requests.
          A more accurate measurement can be obtained by averaging the paint
          times over a long sequence of painting operations.



                                                                        PPPPaaaaggggeeee 5555






iiiimmmmggggttttccccllll((((1111))))                                                            iiiimmmmggggttttccccllll((((1111))))



     vvvvkkkkvvvviiiieeeewwww,,,, vvvvkkkkvvvviiiieeeewwwweeeerrrr

          malloc n


          XXX obsolete?

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     IL(3), IFL(3), ilImage(3)














































                                                                        PPPPaaaaggggeeee 6666